%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                                                               %
%                       Legal Notice                            %
%                                                               %
% This document is copyright (C) Olaf Kirch, okir@monad.swb.de  %
%                                                               %
% For copying conditions, please refer to the file COPYING.	%
%                                                               %
% The author is not liable for any damages, direct or indirect, %
% resulting from the use of information provided in this        %
% document.                                                     %
%                                                               %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% When viewing this document with vi on an 80-columns screen,   %
% do a ':se nonumber' first.                                    %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                                                               %
%               S T A R T   O F   C H A P T E R                 %
%                                                               %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\def\NISplus{{NIS$+$}}

\chapter{The Network Information System}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{nis}
\index{configuring!NIS|(}
\index{Network Information System|see {NIS}}
\index{Yellow Pages|see {NIS}}
\index{YP|see {NIS}}
\index{NIS|(}
\index{network!synchronizing passwords}
\index{hostname!resolution}

When you are running a local area network, your overall goal is usually
to provide an environment to your users that makes the network
transparent.  An important stepping stone to this end is to keep vital
data such as user account information synchronized between all hosts.
We have seen before that for host name resolution, a powerful and
sophisticated service exists, being DNS. For others tasks, there is no
such specialized service. Moreover, if you manage only a small LAN with
no Internet connectivity, setting up DNS may not seem worth the trouble
for many administrators.


This is why Sun developed NIS, the \emph{Network Information System}.
NIS provides generic database access facilities that can be used to
distribute information such as that contained in the \file{passwd} and
\file{groups} files to all hosts on your network.  This makes the
network appear just as a single system, with the same accounts on all
hosts. In a similar fashion, you can use NIS to distribute the hostname
information form \file{/etc/hosts} to all machines on the network.


NIS is based on RPC, and comprises a server, a client-side library, and
several administrative tools.  Originally, NIS was called \emph{Yellow
Pages}, or YP, which is still widely used to informally refer this
service. On the other hand, Yellow Pages is a trademark of British
Telecom, which required Sun to drop that name. As things go, some
names stick with people, and so YP lives on as a prefix to the names
of most NIS-related commands such as \prog{ypserv}, \prog{ypbind},
etc.


\index{Thummler, Swen@Th\"ummler, Swen}
\index{Reber, Tobias}
\index{yp-linux@\prog{yp-linux}}
\index{yps@\prog{yps}}
Today, NIS is available for virtually all \unices{}, and there are even
free implementations of it. One is from the BSD Net-2 release, and has
been derived from a public domain reference implementation donated by
Sun.  The library client code from this release has been in the GNU
\lib{libc} for a long time, while the administrative programs have only
recently been ported to \linux{} by Swen Th\"ummler.\footnote{
  To be reached at \email{swen@uni-paderborn.de}. The NIS clients are
  available as {\tt yp-linux.tar.gz} from \host{sunsite.unc.edu} in
  \file{system/Network}.
} An NIS server is missing from the reference implementation.  Tobias
Reber has written another NIS package including all tools and a server;
it is called \prog{yps}.\footnote{
  The current version (as of this writing) is {\tt yps-0.21} and can
  be obtained from \host{ftp.lysator.liu.se} in the \file{/pub/NYS}
  directory.
}


\index{Eriksson, Peter}
\index{NYS|(}
\index{host.conf@\file{host.conf}}
Currently, a complete rewrite of the NIS code called NYS is being done
by Peter Eriksson,\footnote{
  To be reached at \email{pen@lysator.liu.se}.
} which supports both plain NIS and Sun's much revised \NISplus{}. NYS
not only provides a set of NIS tools and a server, but also adds a whole
new set of library functions which will most probably make it into the
standard \lib{libc} eventually. This includes a new configuration scheme
for hostname resolution that replaces the current scheme using
\file{host.conf}. The features of these functions will be discussed
below.


This chapter will focus on NYS rather than the other two packages, to which
I will refer as the ``traditional'' NIS code. If you do want to run any of
these packages, the instructions in this chapter may or may not be enough.
To obtain additional information, please get a standard book on NIS, such
as Hal Stern's \emph{NFS and NIS} (see~\cite{stern-nfs}).


For the time being, NYS is still under development, and therefore standard
\linux{} utilities such as the network programs or the \prog{login} program
are not yet aware of the NYS configuration scheme.  Until NYS is merged
into the mainstream \lib{libc} you therefore have to recompile all these
binaries if you want to make them use NYS.  In any of these applications'
\file{Makefile}s, specify \file{-lnsl} as the last option before
\file{libc} to the linker. This links in the relevant functions from
\file{libnsl}, the NYS library, instead of the standard C~library.


\section{Getting Acquainted with NIS}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\index{NIS!databases}
\index{NIS!map|(}

NIS keeps database information is in so-called \emph{maps} containing
key-value pairs. Maps are stored on a central host running the NIS
server, from which clients may retrieve the information through various
RPC calls. Quite frequently, maps are stored in DBM files.\footnote{
  DBM is a simple database management library that uses hashing
  techniques to speed up search operations. There's a free DBM
  implementation from the GNU project called \lib{gdbm}, which is
  part of most \linux{} distributions.
}


\index{hosts@\file{hosts}}
\index{passwd@\file{passwd}}
\index{hosts.byname@\file{hosts.byname}}
\index{hosts.byaddr@\file{hosts.byaddr}}
The maps themselves are usually generated from master text files such as
\file{/etc/hosts} or \file{/etc/passwd}. For some files, several maps
are created, one for each search key type. For instance, you may search
the \file{hosts} file for a host name as well as for an IP~address.
Accordingly, two NIS maps are derived from it, called \map{hosts.byname}
and \map{hosts.byaddr}, respectively.  Table~\ref{nis.table.maps} lists
common maps and the files they are generated form.


\begin{table}[htbp]
 \begin{center}
 \begin{tabular}{|l|ll|}
 \hline
 Master File		& Map(s)		& \\
 \hline
 \hline
 \file{/etc/hosts}	& \map{hosts.byname} 	& \map{hosts.byaddr}\\
 \file{/etc/networks}	& \map{networks.byname}	& \map{networks.byaddr}\\
 \file{/etc/passwd}	& \map{passwd.byname}	& \map{passwd.byuid}\\
 \file{/etc/group}	& \map{group.byname}	& \map{group.bygid}\\
 \file{/etc/services}	& \map{services.byname}	& \map{services.bynumber}\\
 \file{/etc/rpc}	& \map{rpc.byname}	& \map{rpc.bynumber}\\
 \file{/etc/protocols}	& \map{protocols.byname}& \map{protocols.bynumber}\\
 \file{/usr/lib/aliases}& \map{mail.aliases}	& \\
 \hline
 \end{tabular}
 \end{center}
 \caption{
  \label{nis.table.maps}
  Some standard NIS maps and the corresponding files.
 }
\end{table}


There are other files and maps you may find support for in some NIS
package or other. These may contain information for applications not
discussed in this book, such as the \map{bootparams} map that may used
by some BOOTP servers, or which currently don't have any function in
\linux{} (like the \map{ethers.byname} and \map{ethers.byaddr} maps).


\index{display!NIS map nicknames}
\index{ypcat@\prog{ypcat}}
\index{NIS!nickname}
\index{NIS!map}
For some maps, people commonly use \emph{nicknames}, which are shorter
and therefore easier to type. To obtain a full list of nicknames
understood by your NIS tools, run the following command:


\begin{tscreen}
\begin{verbatim}
$ ypcat -x
NIS map nickname translation table:
        "passwd" -> "passwd.byname"
        "group" -> "group.byname"
        "networks" -> "networks.byaddr"
        "hosts" -> "hosts.byname"
        "protocols" -> "protocols.bynumber"
        "services" -> "services.byname"
        "aliases" -> "mail.aliases"
        "ethers" -> "ethers.byname"
        "rpc" -> "rpc.bynumber"
        "netmasks" -> "netmasks.byaddr"
        "publickey" -> "publickey.byname"
        "netid" -> "netid.byname"
        "passwd.adjunct" -> "passwd.adjunct.byname"
        "group.adjunct" -> "group.adjunct.byname"
        "timezone" -> "timezone.byname"
\end{verbatim}
\end{tscreen}

\index{NIS!map|)}
\index{NIS!server|(}
\index{ypserv@\prog{ypserv}}
\index{server!ypserv@\prog{ypserv}}
\index{server!NIS}
The NIS server is traditionally called \prog{ypserv}. For an average
network, a single server usually suffices; large networks may choose to
run several of these on different machines and different segments of the
network to relieve the load on the server machines and routers.  These
servers are synchronized by making one of them the \emph{master server},
and the others \emph{slave servers}. Maps will be created only on the
master server's host. From there, they are distributed to all slaves.


\index{NIS!domain|(}
\index{choosing!a NIS domain}
You will have noticed that we have been talking about ``networks''
very vaguely all the time; of course there's a distinctive concept in
NIS that refers to such a network, that is the collection of all hosts
that share part of their system configuration data through NIS: the
\emph{NIS domain}.  Unfortunately, NIS domains have absolutely nothing in
common with the domains we encountered in DNS. To avoid any ambiguity
throughout this chapter, I will therefore always specify which type of
domain I mean.


\index{setting!NIS domain}
\index{domain name!setting NIS}
\index{domainname@\prog{domainname}}
NIS domains have a purely administrative function only. They are mostly
invisible to users, except for the sharing of passwords between all
machines in the domain. Therefore, the name given to a NIS domain is
relevant only to the administrators. Usually, any name will do, as long
as it is different from any other NIS domain name on your local network.
For instance, the administrator at the Virtual Brewery may choose to
create two NIS domains, one for the Brewery itself, and one for the
Winery, which she names \host{brewery} and \host{winery}, respectively.
Another quite common scheme is to simply use the DNS domain name for NIS
as well. To set and display the NIS domain name of your host, you can
use the \prog{domainname} command. When invoked without any argument, it
prints the current NIS domain name; to set the domain name, you must
become super user and type:


\begin{tscreen}
 \# domainname brewery
\end{tscreen}


NIS domains determine which NIS server an application will query. For
instance, the \prog{login} program on a host at the Winery should, of
course, only query the Winery's NIS server (or one of them, if there
were several) for a user's password information; while an application on
a Brewery host should stick with the Brewery's server.


\index{NIS!locating server}
\index{ypbind@\prog{ypbind}}
One mystery now remains to be solved, namely how a client finds out
which server to connect to. The simplest approach would be to have
a configuration file that names the host on which to find the server.
However, this approach is rather inflexible, because it doesn't allow
clients to use different servers (from the same domain, of course), 
depending on their availability. Therefore, traditional NIS
implementations rely on a special daemon called \prog{ypbind} to detect
a suitable NIS server in their NIS domain. Before being able to perform
any NIS queries, any application first finds out from \prog{ypbind}
which server to use.


\prog{ypbind} probes for servers by broadcasting to the local IP~network;
the first to respond is assumed to be the potentially fastest one and
will be used in all subsequent NIS queries. After a certain interval has
elapsed, or if the server becomes unavailable, \prog{ypbind} will
probe for active servers again.


Now, the arguable point about dynamic binding is that you rarely need
it, and that it introduces a security problem: \prog{ypbind}
blindly believes whoever answers, which could be a humble NIS server
as well as a malicious intruder. Needless to say this becomes especially
troublesome if you manage your password databases over NIS.  To guard
against this, NYS does \emph{not} use \prog{ypbind} by default, but
rather picks up the server host name from a configuration file.

\index{NIS!domain|)}
\index{NIS!server|)}


\section{NIS versus \NISplus}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{nis.nisplus}
\index{NIS+@NIS$+$}

NIS and \NISplus{} share little more than their name and a common goal.
\NISplus{} is structured in an entirely different way. Instead of a flat
name space with disjoint NIS domains, it uses a hierarchical name space
similar to that of DNS. Instead of maps, so called \emph{tables} are
used that are made up of rows and columns, where each row represents an
object in the \NISplus{} database, while the columns cover those properties
of the objects that \NISplus{} knows and cares about. Each table for a
given \NISplus{} domain comprises those of its parent domains. In addition,
an entry in a table may contain a link to another table. These features
make it possible to structure information in many ways.


Traditional NIS has an RPC version number of~2, while \NISplus{} is
version~3.


\NISplus{} does not seem to be very widely used yet, and I don't really
know that much about it. (Well, almost nothing). For this reason, we
will not deal with it here. If you are interested in learning more about
it, please refer to Sun's \NISplus{} administration manual
(\cite{nisplus}).


\section{The Client Side of NIS}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{nis.clients}
\index{NIS!client|(}
\index{NIS!map}

If you are familiar with writing or porting network applications, you
will notice that most NIS maps listed above correspond to library
functions in the C~library. For instance, to obtain \file{passwd}
information, you generally use the \func{getpwnam(3)} and
\func{getpwuid(3)} functions which return the account information
associated with the given user name or numerical user id, repsectively.
Under normal circumstances, these functions will perform the requested
lookup on the standard file, such as \file{/etc/passwd}.


A NIS-aware implementation of these functions, however, will modify this
behavior, and place an RPC call to have the NIS server look up the user
name or id. This happens completely transparent to the application.  The
function may either ``append'' the NIS map to or ``replace'' the
original file with it. Of course, this does not refer to a real
modification of the file, it only means that it \emph{appears} to the
application as if the file had been replaced or appended to.


For traditional NIS implementations, there used to be certain
conventions as to which maps replaced, and which were appended to the
original information.  Some, like the \map{passwd} maps, required kludgy
modifications of the \file{passwd} file which, when done wrong, would
open up security holes. To avoid these pitfalls, NYS uses a general
configuration scheme that determines whether a particular set of client
functions uses the original files, NIS, or \NISplus{}, and in which
order. It will be described in a later section of this chapter.

\index{NIS!client|)}


\section{Running a NIS Server}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{nis.server}
\index{configuring!NIS}
\index{NIS!server|(}

After so much theoretical techno-babble, it's time to get our hands
dirty with actual configuration work. In this section, we will cover the
configuration of a NIS server. If there's already a NIS server running
on your network, you won't have to set up your own server; in this case,
you may safely skip this section.


\begin{quote}
 \blackdiamond
 Note that if you are just going to experiment with the server, make
 sure you don't set it up for a NIS domain name that is already in use
 on your network. This may disrupt the entire network service and make a
 lot of people very unhappy, and very angry.
\end{quote}


There are currently two NIS servers freely available for \linux{}, one
contained in Tobias Reber's \file{yps} package, and the other in Peter
Eriksson's \file{ypserv} package. It shouldn't matter which one you run,
regardless of whether you use NYS or the standard NIS client code that
is in \file{libc} currently. At the time of this writing, the code for
the handling of NIS slave servers seems to be more complete in
\file{yps}. So if you have to deal with slave servers, \file{yps} might
be a better choice.


After installing the server program (\prog{ypserv}) in \file{/usr/sbin},
you should create the directory that is going to hold the map files your
server is to distribute. When setting up a NIS domain for the
\host{brewery} domain, the maps would go to \file{/var/yp/brewery}.  The
server determines if it is serving a particular NIS domain by checking
if the map directory is present. If you are disabling service for some
NIS domain, make sure to remove the directory as well.


\index{NIS!creating maps}
\index{creating!NIS maps}
Maps are usually stored in DBM files to speed up lookups. They are
created from the master files using a program called \prog{makedbm} (for
Tobias' server) or \prog{dbmload} (for Peter's server). These may not be
interchangeable. Transforming a master file into a form parseable by
\prog{dbmload} usually requires some \prog{awk} or \prog{sed} magic,
which tend to be a little tedious to type and hard to remember.
Therefore, Peter Eriksson's \file{ypserv} package contains a Makefile
(called \file{ypMakefile}) that does all these jobs for you. You should
install it as \file{Makefile} in your map directory, and edit it to
reflect the maps you want to distribute. Towards the top of the file,
you find the \keyword{all} target that lists the services \prog{ypserv}
is to offer.  By default, the line looks something like this:


\begin{tscreen}
\begin{verbatim}
all: ethers hosts networks protocols rpc services passwd group netid
\end{verbatim}
\end{tscreen}


\index{checking!NIS}
If you don't want to produce the \file{ethers.byname} and
\file{ethers.byaddr} maps, for example, simply remove the
\keyword{ethers} prerequisite from this rule. To test your setup, it may
suffice to start with just one or two maps, like the \file{services.*}
maps.


After editing the \file{Makefile}, while in the map directory, type
``\term{make}''. This will automatically generate and install the maps.
You have to make sure to update the maps whenever you change the master
files, otherwise the changes will remain invisible to the network.


\index{checking!NIS}
The next section explains how to configure the NIS client code.  If your
setup doesn't work, you should try to find out whether any requests
arrive at your server or not. If you specify the \option{-D} command
line flag to the NYS server, it prints debugging messages to the console
about all incoming NIS queries, and the results returned. These should
give you a hint as to where the problem lies. Tobias' server has no such
option.



\index{NIS!server|)}


\section{Setting up a NIS Client with NYS}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{nis.yp}
\index{configuring!NIS}
\index{NIS!client|(}

Throughout the remainder of this chapter, we will cover the
configuration of a NIS client.

\index{yp.conf@\file{yp.conf}|(}
\index{setting!NIS domain}
Your first step should be to tell NYS which server to use for NIS
service, setting it in the \file{/etc/yp.conf} configuration file.
A very simple sample file for a host on the Winery's network may look
like this:


\begin{tscreen}
\begin{verbatim}
# yp.conf - YP configuration for NYS library.
#
domainname winery
server vbardolino 
\end{verbatim}
\end{tscreen}


The first statement tells all NIS clients that they belong to the
\host{winery} NIS domain.  If you omit this line, NYS will use the
domain name you assigned your system through the \prog{domainname}
command.  The \keyword{server} statement names the NIS server to use.
Of course, the IP address corresponding to \host{vbardolino} must be set
in the \file{hosts} file; alternatively, you may use the IP~address
itself with the \keyword{server} statement.


In the form shown above, the \keyword{server} command tells NYS to use the
named server whatever the current NIS domain may be. If, however, you are
moving your machine between different NIS domains frequently, you may want
to keep information for several domains in the \file{yp.conf} file. You can
have information on the servers for various NIS domains in \file{yp.conf}
by adding the NIS domain name to the \keyword{server} statement.  For
instance, you might change the above sample file for a laptop to look like
this:


\begin{tscreen}
\begin{verbatim}
# yp.conf - YP configuration for NYS library.
# 
server vbardolino winery
server vstout     brewery
\end{verbatim}
\end{tscreen}


This allows you to bring up the laptop in any of the two domains by simply
setting the desired NIS domain at boot time through the \prog{domainname}
command.
\index{yp.conf@\file{yp.conf}|)}


\index{ypcat@\prog{ypcat}}
\index{checking!NIS}
After creating this basic configuration file and making sure it is
world-readable, you should run your first test to check if you can
connect to your server. Make sure to choose any map your server
distributes, like \map{hosts.byname}, and try to retrieve it by using
the \prog{ypcat} utility. \prog{ypcat}, like all other administrative
NIS tools, should live in \file{/usr/sbin}.


\begin{tscreen}
\begin{verbatim}
# ypcat hosts.byname
191.72.2.2      vbeaujolais  vbeaujolais.linus.lxnet.org
191.72.2.3      vbardolino   vbardolino.linus.lxnet.org
191.72.1.1      vlager       vlager.linus.lxnet.org
191.72.2.1      vlager       vlager.linus.lxnet.org
191.72.1.2      vstout       vstout.linus.lxnet.org
191.72.1.3      vale         vale.linus.lxnet.org
191.72.2.4      vchianti     vchianti.linus.lxnet.org
\end{verbatim}
\end{tscreen}


\index{rpcinfo@\prog{rpcinfo}}
The output you get should look somthing like that shown above. If you
get an error message instead that says ``\message{Can't bind to server
which serves domain}'' or something similar, then either the NIS domain
name you've set doesn't have a matching server defined in
\file{yp.conf}, or the server is unreachable for some reason. In the
latter case, make sure that a \prog{ping} to the host yields a positive
result, and that it is indeed running a NIS server. You can verify the
latter by using \prog{rpcinfo}, which should produce the following
output:


\begin{tscreen}
 \# rpcinfo -u {\sl serverhost} ypserv\\
 program 100004 version 2 ready and waiting
\end{tscreen}



\section{Choosing the Right Maps}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{nis.nsswitch}
\index{nsswitch.conf@\file{nsswitch.conf}|(}
\index{choosing!NIS maps}

Having made sure you can reach the NIS server, you have to decide which
configuration files to replace or augment with NIS maps. Commonly, you
will want use NIS maps for the host and password lookup functions. The
former is especially useful if you do not run BIND. The latter permits
all users to log into their account from any system in the NIS domain;
this usually requires sharing a central \file{/home} directory between
all hosts via NFS. It is explained detail in section~\ref{nis.passwd}
below. Other maps, like \file{services.byname}, aren't such
a dramatic gain, but save you some editing work if you install any
network applications that use a service name that's not in the
standard \file{services} file.


Generally, you want to have some freedom of choice when a lookup
function uses the local files, and when it queries the NIS server.
NYS allows you to configure the order in which a function accesses these
services. This is controlled through the \file{/etc/nsswitch.conf} file,
which stands for \emph{Name Service Switch} but of course isn't limited
to the name service.  For any of the data lookup functions supported by
NYS, it contains a line naming the services to use.


\index{services.byname@\file{services.byname}}
\index{hosts.byname@\file{hosts.byname}}
The right order of services depends on the type of data. It is unlikely
that the \file{services.byname} map will contain entries differing from those
in the local \file{services} file; it may only contain more. So a good
choice may be to query the local files first, and check NIS only if
the service name wasn't found. Hostname information, on the other hand,
may change very frequently, so that DNS or the NIS server should always
have the most accurate account, while the local \file{hosts} file
is only kept as a backup if DNS and NIS should fail. In this case,
you would want to check the local file last.


The example below shows how to configure \func{gethostbyname(2)},
\func{gethostbyaddr(2)}, and \func{getservbyname(2)} functions as
described above. They will try the listed services in turn; if a lookup
succeeds, the result is returned, otherwise the next service is tried.


\begin{tscreen}
\begin{verbatim}
# small sample /etc/nsswitch.conf
#
hosts:     nis dns files 
services:  files nis
\end{verbatim}
\end{tscreen}


The complete list of services that may be used with an entry in the
\file{nsswitch.conf} file is shown below. The actual maps, files,
servers and objects being queried depend on the entry name. 


\begin{dispitems}
 \ditem[\keyword{nisplus} or \keyword{nis+}]
 	Use the \NISplus{} server for this domain. The location of the
 	server is obtained from the \file{/etc/nis.conf} file.

 \ditem[\keyword{nis}]
 	Use the current NIS server of this domain. The location of the
 	server queried is configured in the \file{yp.conf} file as shown
 	in the previous section.  For the \keyword{hosts} entry, the
 	maps \map{hosts.byname} and \map{hosts.byaddr} are queried.

 \ditem[\keyword{dns}]
 	Use the DNS name server. This service type is only useful with
 	the \keyword{hosts} entry. The name servers queried are still
 	determined by the standard \file{resolv.conf} file.

 \ditem[\keyword{files}]
 	Use the local file, such as the \file{/etc/hosts} file for the
 	\keyword{hosts} entry.

 \ditem[\keyword{dbm}]
	Look up the information from DBM files located in
	\file{/var/dbm}.  The name used for the file is that of the
	corresponding NIS map.

\end{dispitems}


Currently, NYS supports the following \file{nsswitch.conf} entries:
\keyword{hosts}, \keyword{networks}, \keyword{passwd}, \keyword{group},
\keyword{shadow}, \keyword{gshadow}, \keyword{services},
\keyword{protocols}, \keyword{rpc}, and \keyword{ethers}. More entries
are likely to be added.

% \keyword{aliases}, 
% \keyword{netmasks}, 
% \keyword{publickey}, 
% \keyword{netid}, 


Figure~\ref{nis.fig.switch} shows a more complete example which
introduces another feature of \file{nsswitch.conf}: the
\keyword{[NOTFOUND=return]} keyword in the \keyword{hosts} entry tells
NYS to return if the desired item couldn't be found in the NIS or DNS
database.  That is, NYS will continue and search the local files 
\emph{only} if calls to the NIS and DNS servers failed for some other
reason. The local files will then only be used at boot time and as a
backup when the NIS server is down.


\begin{figure}[htbp]
\begin{tscreen}
\begin{verbatim}
# /etc/nsswitch.conf
#
hosts:      nis dns [NOTFOUND=return] files
networks:   nis [NOTFOUND=return] files

services:   files nis
protocols:  files nis
rpc:        files nis
\end{verbatim}
\end{tscreen}
 \caption{
  \label{nis.fig.switch}
  Sample \file{nsswitch.conf} file.
 }
\end{figure}

\index{nsswitch.conf@\file{nsswitch.conf}|)}



\section{Using the \file{passwd} and \file{group} Maps}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{nis.passwd}
\index{NIS!passwd maps@\file{passwd} maps|(}
\index{passwd.byname@\file{passwd.byname}}
\index{passwd.byuid@\file{passwd.byuid}}
\index{group.byname@\file{group.byname}}
\index{group.bygid@\file{group.bygid}}
\index{passwords!network-wide|(}
\index{network!passwords}
\index{LAN!passwords}

One of the major applications of NIS is in synchronizing user and
account information on all hosts in a NIS domain. To this end, you
usually keep only a small local \file{/etc/passwd} file, to which
the site-wide information from the NIS maps is appended. However,
simply enabling NIS lookups for this service in \file{nsswitch.conf}
is not nearly enough.


When relying on the password information distributed by NIS, you first
have to make sure that the numeric user id's of any users you have in
your local \file{passwd} file match the NIS server's idea of user id's.
You will want this for other purposes as well, like mounting NFS volumes
from other hosts in your network.


If any of the numeric ids in \file{/etc/passwd} or \file{/etc/group}
deviate from those in the maps, you have to adjust file ownerships for
all files that belong to that user. First you should change all uids and gids
in \file{passwd} and \file{group} to the new values; then find all files
that belong to the users just changed, and finally change their
ownership.  Assume \user{news} used to have a user id of 9, and
\user{okir} had a user id of 103, which were changed to some other
value; you could then issue the following commands:


\begin{tscreen}
\begin{verbatim}
 # find / -uid   9 -print >/tmp/uid.9
 # find / -uid 103 -print >/tmp/uid.103
 # cat /tmp/uid.9   | xargs chown news
 # cat /tmp/uid.103 | xargs chown okir
\end{verbatim}
\end{tscreen}


It is important that you execute these commands with the \emph{new}
\file{passwd} file installed, and that you collect all file names before
you change the ownership of any of them. To update the group ownerships
of files, you will use a similar command.


Having done this, the numerical uid's and gid's on your system will
agree with those on all other hosts in your NIS domain.  The next step
will be to add configuration lines to \file{nsswitch.conf} that enables
NIS lookups for user and group information:


\begin{tscreen}
\begin{verbatim}
# /etc/nsswitch.conf - passwd and group treatment
passwd: nis files
group:  nis files
\end{verbatim}
\end{tscreen}


This makes the \prog{login} command and all its friends first query
the NIS maps when a user tries to log in, and if this lookup fails,
fall back to the local files. Usually, you will remove almost all
users from your local files, and only leave entries for \user{root}
and generic accounts like \user{mail} in it.  This is because some
vital system tasks may require to map uids to user names or vice
versa.  For example, administrative \prog{cron} jobs may execute the
\file{su} command to temporarily become \user{news}, or the UUCP
subsystem may mail a status report.  If \user{news} and \user{uucp}
don't have entries in the local \file{passwd} file, these jobs will
fail miserably during a NIS brownout.


There are two big caveats in order here: on one hand, the setup as
described up to here only works for login suites that don't use shadow
password, like those included in the \file{util-linux} package. The
intricacies of using shadow passwords with NIS will be covered below.
On the other hand, the login commands are not the only ones that
access the \file{passwd} file~-- look at the \prog{ls} command which
most people use almost constantly. Whenever doing a long listing,
\prog{ls} will display the symbolic names for user and group owners of
a file; that is, for each uid and gid it encounters, it will have to
query the NIS server once. This will slow things down rather badly if
your local network is clogged, or, even worse, when the NIS server is
not on the same physical network, so that datagrams have to pass
through a router.


Still, this is not the whole story yet. Imagine what happens if a user
wants to change her password. Usually, she will invoke \prog{passwd},
which reads the new password and updates the local \file{passwd}
file. This is impossible with NIS, since that file isn't available
locally anymore, but having users log into the NIS server whenever they
want to change their password is not an option either. Therefore, NIS
provides a drop-in replacement for \prog{passwd} called \prog{yppasswd},
which does the analoguous thing in the presence of NIS. To change the
password on the server host, it contacts the \prog{yppasswdd} daemon on
that host via RPC, and provides it with the updated password
information. Usually, you install \prog{yppasswd} over the normal
program by doing something like this:


\begin{tscreen}
\begin{verbatim}
# cd /bin
# mv passwd passwd.old
# ln yppasswd passwd
\end{verbatim}
\end{tscreen}


At the same time you have to install \prog{rpc.yppasswdd} on the server
and start it from \file{rc.inet2}.  This will effectively hide any of
the contortions of NIS from your users.


% Be also warned that while NYS is still a separate library and hasn't yet
% made it into the standard \lib{libc}, using NIS support for the
% \file{passwd} information is only a theoretical option.  This will
% hopefully change soon.


\index{passwords!network-wide|)}
\index{NIS!passwd maps@\file{passwd} maps|)}

\section{Using NIS with Shadow Support}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{nis.shadow}
\index{NIS!and shadow passwords}

There is no NIS support yet for sites that use the shadow login suite.
John F.~Haugh, the author of the shadow suite, recently released a
version of the shadow library functions covered by the GNU Library GPL
to \ngrp{comp.sources.misc}. It already has some support for NIS, but
it isn't complete, and the files haven't been added to the standard C
library yet. On the other hand, publishing the information from
\file{/etc/shadow} via NIS kind of defeats the purpose of the shadow
suite.


Although the NYS password lookup functions don't use a \file{shadow.byname}
map or anything likewise, NYS supports using a local \file{/etc/shadow}
file transparently. When the NYS implementation of \func{getpwnam} is
called to look up information related to a given login name, the facilities
specified by the \keyword{passwd} entry in \file{nsswitch.conf} are
queried. The \keyword{nis} service will simply look up the name in the
\file{passwd.byname} map on the NIS server. The \keyword{files} service,
however, will check if \file{/etc/shadow} is present, and if so, try to
open it. If none is present, or if the user doesn't have \user{root}
privilege, if reverts to the traditional behavior of looking up the user
information in \file{/etc/passwd} only. However, if the \file{shadow} file
exists and can be opened, NYS will extract the user password from
\file{shadow}. The \func{getpwuid} function is implemented accordingly.  In
this fashion, binaries compiled with NYS will deal with a local
the shadow suite installation transparently.



\section{Using the Traditional NIS Code}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{nis.old-code}
\index{NIS!traditional code}

If you are using the client code that is in the standard \file{libc}
currently, configuring a NIS client is a little different. On one
hand, it uses a \prog{ypbind} daemon to broadcast for active servers
rather than gathering this information from a configuration file.
You therefore have to make sure to start \prog{ypbind} at boot
time. It must be invoked after the NIS domain has been set and the
RPC portmapper has been started. Invoking \prog{ypcat} to test the
server should then work as shown above.


\index{portmapper failure (error message)}
Recently, there have been numerous bug reports that NIS fails with
an error message saying ``\term{clntudp\_create: RPC: portmapper
failure - RPC: unable to receive}''. These are due to an incompatible
change in the way \prog{ypbind} communicates the binding information
to the library functions. Obtaining the latest sources for the NIS
utilities and recompiling them should cure this problem.\footnote{
 The source for \file{yp-linux} can be gotten from
 \host{ftp.uni-paderborn.de} in directory \file{/pub/Linux/LOCAL}.
}


\index{NIS!passwd maps@\file{passwd} maps}
\index{network!passwords}
\index{LAN!passwords}
Also, the way traditional NIS decides if and how to merge NIS
information with that from the local files deviates from that used by
NYS. For instance, to use the NIS password maps, you have to include
the following line somewhere in your \file{/etc/passwd} map:


\begin{tscreen}
 +:*:0:0:::
\end{tscreen}


\index{host.conf@\file{host.conf}}
\index{network!hostname resolution}
\index{LAN!hostname resolution}
\index{hostname!resolution}
This marks the place where the password lookup functions ``insert'' the
NIS maps.  Inserting a similar line (minus the last two colons) into
\file{/etc/group} does the same for the \file{group.*} maps.  To use the
\file{hosts.*} maps distributed by NIS, change the \keyword{order} line
in the \file{host.conf} file. For instance, if you want to use NIS, DNS,
and the \file{/etc/hosts} file (in that order), you need to change the
line to


\begin{tscreen}
 order yp bind hosts
\end{tscreen}


The traditional NIS implementation does not support any other maps
at the moment.


\index{NIS!client|)}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\index{configuring!NIS|)}
\index{NYS|)}
\index{NIS|)}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%                                                             %%
%%              E N D   O F   C H A P T E R                    %%
%%                                                             %%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
